POST 1

[u]Introduction[/u]

[i]Kerkerkruip[/i], my IF roguelike, lends itself perfectly to user-contributed content. It can always be improved by having more items, more monsters, more interesting things that can happen; and these can be thought up and programmed in relative isolation. Since Dannii set up a [url=https://github.com/i7]Github[/url] repository for the whole ATTACK and [i]Kerkerkruip[/u] code, getting hold of the latest development code has become really easy.

(If you're a complete newbe to repositories and version control systems, as I am, you may want to check out [url=http://windows.github.com/]Github for Windows[/url], a nice graphical shell. It is even possible just download the files by hand from the website -- it's only about 15 files, and you can commit any finished code by email.)

But, of course, [i]Kerkerkruip[/i] is a big game consisting of a lot of code. Even if you know some Inform 7, it may look pretty intimidating. So in order to lower the threshold and encourage people to join in the development of [i]Kerkerkruip[/i], I am launching a series of [i]Kerkerkruip[/i] programming tutorials, in which I will talk about the creation of new things for the game. I hope you'll enjoy them!

[u]Preliminaries[/u]

This is not a tutorial for programming in Inform 7. I'll assume you already know the language; if you don't, there are several great tutorials out there (including the Inform 7 manual).

I'll also assume that you have downloaded the source code from Github, and can compile the game.

[u]But wait... will my code be accepted?[/u]

That's a good question. If you write some code for [i]Kerkerkruip[/i], do I guarantee that it will be accepted into the game? (And if I don't, why would you spend time writing it?)

No, I can't absolutely guarantee that we will accept your code, if you decide to write some. Contributions do need to fit into the existing game and its philosophy. So for instance, here are some things that probably would [i]not[/i] be acceptable:

* A monster with an ability that just instantly kills the player 10% of the time. We want [i]Kerkerkruip[/i] to be tactical, not based on pure luck.
* A weapon that is a lot better than all the other weapons in the game. We want [i]Kerkerkruip[/i] to be about interesting choices, not about no-brainers.
* An item that allows you to keep all powers you already have, even if you kill a higher level monster later. This would disrupt the basic strategy of the game too much (and it would be overpowered).
* A giant marshmallow man. That would be silly. Which is fine, but it wouldn't fit the atmosphere of the game.
* And of course anything that is racist, sexist, and so on.

But while not everything goes, a lot does. [i]Kerkerkruip[/i] doesn't insist on a unified theme, and there are a lot of variables that can be tweaked to balance any contribution against what is already in the game. And if we feel that something is in itself acceptable, but is really weird, we can just make it rare -- the game will be strengthened by the addition of strange things that the player comes across only occasionally. So the acceptance policy will certainly be liberal.

(Coming to think of it, there might even be a place for that item that allows you to keep all powers you already have, though it would only appear in extraordinary circumstances.)

Of course, the [i]best[/i] thing to do is just to discuss your idea before you start implementing it, especially if it will be a lot of work. You can email me, or make a post in this thread.

[u]Onwards![/u]

Yes, onwards! But that's something for the next post.



POST 2

[b]TUTORIAL 1: Making a weapon[/b]

[u]Coming up with an idea[/u]

New monsters are probably what we would like to have most in [i]Kerkerkruip[/i], but monsters are difficult. So we'll start by doing something that is simpler: making a new weapon.

Now, before we start coding, we need to come up with a good idea. What we want to have is a weapon that is different from the weapons that are already in the game; and that is different in a way that creates interesting tactical choices. (Tactical choices are not the [i]only[/i] reason to put something in the game, but it's a very important one.)

I suggest we implement "the dagger of the double strike", which has the following characteristics:

* It is low-damage weapon. Without a special ability, it would be among the worst weapons in the game.
* If you miss with the dagger of the double strike, you immediately strike another blow at your enemy. (Once only; this second strike no longer benefits from any concentration bonus.)

This weapon would be bad against opponents with damage reduction, such as the ravenous armadillo; but it would be good in cases where hitting our opponent is more important than dealing a lot of damage, for instance because we need to break the opponent's concentration.

[u]The dagger kind[/u]

The best way to start coding a new item is by looking at the code of an existing item. All weapons, and in fact almost everything the player can carry around, is found in the extension called "Kerkerkruip Items". So we open up this extenion, and search for a dagger. First, we'll find the code that defines daggers in general, which reminds us that daggers get better attack and damage bonuses from tension. We also find this numerical information:
[code]The damage die of a dagger is usually 3.
The weapon attack bonus of a dagger is usually -1.
The dodgability of a dagger is usually 3.
The passive parry max of a dagger is usually 1.
The active parry max of a dagger is usually 1.
The weapon damage bonus of a dagger is usually 0.[/code]
What does that mean? You can find all of this in the ATTACK manual, but let's review it.

* The damage die is the size of the die that is rolled to determine damage. A damage die of 3 means that the basic damage is a random number between 1 and 3; a damage die of 6 that the basic damage is between 1 and 6, and so on.
* The weapon attack bonus is a bonus you receive to your attack roll.
* The dodgability is the attack penalty you will get when you attack with a weapon and the defender dodges.
* On the other hand, when your opponent parries, you will get an attack penalty equal to either the passive parry max of your weapon, or the active parry max of your opponent's weapon, whichever is lower. For the example of the dagger: it's easy to parry a dagger (so you could get up to a 3 attack penalty if the opponent parries), but it's not easy to parry [i]with[/i] a dagger (so someone using a dagger to parry will never give his opponent more than 1 attack penalty). 
* The weapon damage bonus is a bonus to the damage you do.

It's good to know this stuff, because we might want to tweak our dagger of the double strike.

[u]A basic dagger[/u]

Looking further, we find the code for the gorgeous dagger, one of the simplest items in the game.
[code]Section - Gorgeous dagger

The gorgeous dagger is a minor dagger.
The gorgeous dagger is civilised.
The gorgeous dagger is iron.

The description of the gorgeous dagger is "Adorned with gold and a large emerald at the end of the hilt, this dagger is not only beautiful, but also perfect for precise attacks in tense situations. The decadence of its design proves it to be of Yahvinnean origin.".[/code]
Here we see a couple of things. First, items should be declared as being either "minor", "major", "epic", "special", "unique", or "non-treasure". Non-treasure is the standard, and anything that is non-treasure will not be placed in the dungeon by the treasure generation rules. Special and unique aren't really in use yet, so let's not worry about them for now. This leaves us with minor, major, and epic. As the names suggest, minor items are the least powerful, while epic items are the most powerful. In addition, epic items should change your playstyle significantly when used. Examples of minor items are the essence of rage, the tormenting necklace, and the fearsome axe. Examples of major items are the executioner's axe, the magical space, and the boots of the war dance. Examples of epic items are the cloak of shadows, the glass cannon, and the essence of addiction.

Second, and item should have a "mood". The moods are civilised, religious, barren, deathly, elemental, magical, alchemical and non-mood. Moods have no effect in play, but they ensure that items are more often placed in rooms with the same mood, that is, rooms where they thematically belong. For instance, Drakul's lifeblood (a deahtly epic item) will be found in the Crypt (a deathly room) more often than in the Temple of Aite (a religious room).

Third, we should give the item a material. The materials are iron, silver, paper, cloth, wood, leather, flesh, glass, stone, dragon skin, radiance, adamant, and vapour. Materials are already used for a couple of things (for instance, calculating how fast something dissolves in the stomach of the armadillo), and I have bigger plans with them in the future.

Knowing this, we can now write down the basic definition of our dagger.
[code]Section - Dagger of the double strike

The dagger of the double strike is a major dagger.
The dagger of the double strike is civilised.
The dagger of the double strike is iron.

The damage die of the dagger of the double strike is 1.

The description of the dagger of the double strike is "The dagger looks dull and far from dangerous. But appearances deceive, for this weapon has been imbued with a dangerous magic.".

The special weapon info of the dagger of the double strike is "; allows its wielder to strike again immediately if the first attack did no damage[run paragraph on]".
[/code]
Our dagger has an atrocious damage output of 1 damage; though concentration and tension can increase this. This makes it perhaps the worst weapon in the game, except for the very powerful ability we haven't programmed yet. That ability (a second chance to break your enemy's concentration!) is probably so good that I have decided to make it a "major" item. If we find out in practice that it isn't good enough, we can either lower it to a minor item or increase its usefulness in some other way.

I've also used the "special weapon info" property to explain the dagger's power in more technical detail to the player.

[u]Testing our dagger[/u]

We should now save the extension in which we put the code (this is crucial, otherwise Inform will use the unsaved version), start the game, and use the cheat command "purloin double strike".

Well, the description looks good, and the dagger works! Of course, we haven't programmed the most important part of the item yet, so it's pretty useless right now. Let's get on to that.

[u]The special ability[/u]

Now we write the special ability:
[code]Making-double-strike is a truth state that varies. Making-double-strike is false.

Last after reporting an actor hitting (this is the hit again with the dagger of double strike rule):
	if the global attacker weapon is the dagger of double strike:
		if making-double-strike is false:
			if the attack damage is 0:
				if the global attacker is alive and the global defender is alive:
					now making-double-strike is true;
					say "The dagger of the double strike slashes out again!";
					try the global attacker hitting the global defender;
					now making-double-strike is false.[/code]
If we are well acquainted with (the newest version of) ATTACK, we will know that a "last after reporting an actor hitting" rule is the very last thing that will run when someone hits someone. Which is exactly what we need here, of course.

The "global attacker" weapon is the weapon used to attack, and the "global attacker" and the "global defender" are the guy who attacks and the guy who defends respectively. The "attack damage" is the amount of damage that was dealt. The conditions should explain themselves; e.g., we don't want to double strike if either the attacker or the defender is dead. (But how can either of them be dead if the previous attack missed? Well, there might be special rules that allow this to happen, for instance, a weapon that deals damage to the attacker whenever it is used. We need to be careful and take nothing for granted.) The making-double-strike variable ensures that only one double strike is made, not a series that terminates only once a hit is scored.

Having written this code, we run the game again and test the dagger. It turns out to be much more powerful than I originally thought, because the defender doesn't get an extra turn to dodge or parry. This means that the second attack hits very often. In fact, it hits too often, so I decide to cripple the dagger a little more:
[code]The weapon attack bonus of the dagger of double strike is -2.[/code]
That's it. The dagger of double strike is ready to see some action. During play it might still turn out to be either too powerful or not powerful enough, in which case I'll come back to tweak it; but for now, we have an interesting new addition to [i]Kerkerkruip[/i].